Melodee API

This page documents the native Melodee REST API. For an overview of all available APIs (Melodee, OpenSubsonic, and Jellyfin), see the API Overview page.

For interactive API documentation and testing, visit the Scalar UI at /scalar/v1 when Melodee is running. You can also download the OpenAPI specification at /openapi/v1.json.

Authentication

All native endpoints (unless explicitly noted) require an API key associated with the user making the request. Provide it via header:

Authorization: Bearer <user-api-key-guid>

If an endpoint returns 401 with { error: "Authorization token is invalid" }, verify the key or that the user is not locked. A 403 indicates the user is locked or blacklisted.

Versioning

Prefix: /api/v1/ (future versions will increment the path number; multiple versions may run side‑by‑side).

Common Response Shape

Paginated list endpoints respond with:

{
	"meta": {
		"totalCount": <int>,
		"pageSize": <int>,
		"page": <int>,
		"totalPages": <int>
	},
	"data": [ ... ]
}

Errors:

{ "error": "Message" }

Endpoints

System

GET /api/v1/System/info

Returns:

{
	"serverType": "Melodee",
	"name": "Melodee API",
	"majorVersion": 1,
	"minorVersion": 0,
	"patchVersion": 0
}

Artists

Base: /api/v1/artists

Playlists

Base: /api/v1/playlists

User

Base: /api/v1/user

Endpoints for the currently authenticated user.

Shares

Base: /api/v1/shares

Requests

Base: /api/v1/requests

Queue

Base: /api/v1/queue

Charts

Base: /api/v1/charts

Genres

Base: /api/v1/genres

Albums

Base: /api/v1/Albums

Notes:

• orderDirection: asc or desc (default desc).
• orderBy defaults to CreatedAt.

Songs

Base: /api/v1/Songs

Streaming:

• This path omits the /api/v1 version prefix intentionally for compatibility.
• authToken is a time‑limited HMAC token (client generates using user public key) encoded Base64.
• Supports Range: bytes=... for efficient seeking & partial delivery.

Search

Base: /api/v1/Search

SearchRequest Fields (selected):

Response returns aggregated counts + typed collections. User ratings / starred info are included where applicable.

Scrobble

Base: /api/v1/Scrobble

scrobbleType values: NowPlaying, Played. On success returns 200 with empty body.

Authorization & Blacklists

Several endpoints enforce additional checks:

• User locked -> 403
• Blacklisted IP / Email (Search & Songs modifications, Streaming) -> 403 with { error: "User is blacklisted" }

Rate / Concurrency Limits

Streaming uses an internal limiter keyed per user to prevent excessive simultaneous streams (configurable in future releases). Exceeding yields HTTP 429.

Status Codes Summary

Example: Paginated Albums

Request:

GET /api/v1/Albums?page=1&pageSize=25&orderBy=CreatedAt&orderDirection=desc
Authorization: Bearer <apiKey>

Response (truncated):

{
	"meta": { "totalCount": 10234, "pageSize": 25, "page": 1, "totalPages": 410 },
	"data": [ { "id": "...", "name": "...", "songCount": 12, ... } ]
}

Example: Stream a Song

1. Obtain user public key & generate an HMAC based timed token (client library forthcoming).
2. Issue request:

   GET /song/stream/<songId>/<userId>/<authToken>
   Range: bytes=0-524287
   

3. Handle 206 partial response & continue ranged requests as needed.

Recent Refactors

The API layer was re‑architected to delegate operations to consolidated domain services (authentication, ratings, playlists, search, caching) reducing duplication and improving reliability without changing external contracts.

Official Clients & Ecosystem

MeloAmp Details

• Tech: Electron + React + Material‑UI + TypeScript.
• Auth: JWT (obtained via native login against Melodee API) stored locally.
• Features mapping to endpoints:
  • Albums/Songs browsing -> Albums, Songs, Search endpoints.
  • Star / rating actions -> Songs/starred and Songs/setrating.
  • Scrobbling (play / complete) -> Scrobble endpoint.
  • Queue operations are client‑side; future server playlist sync may use a native playlist endpoint (planned).
• Theming & equalizer are client-resident (no server configuration needed).

Melodee Player (Android) Details

• Tech: Kotlin, Jetpack Compose, Clean Architecture (data/domain/presentation), Media3 ExoPlayer, Retrofit.
• Android Auto: MediaBrowserService + MediaSession integration; voice command intents map to search + playback calls using Search and Songs endpoints.
• Caching: May locally cache minimal metadata for smooth navigation; server remains source of truth.
• Scrobbling: Dispatches NowPlaying then Played events to represent progress and completion.
• Supports pull‑to‑refresh to re-query / invalidate local caches via If-None-Match (future optimization with etag headers).

Homelab API Integration

For homelab environments, the API enables several useful integrations:

Automation Scripts:

• Automated library management
• Scheduled metadata updates
• Custom reporting and statistics

Home Automation:

• Integration with home automation systems (Home Assistant, OpenHAB)
• Voice control via custom integrations
• Presence detection for automatic playback

Monitoring:

• System health checks
• Library statistics tracking
• User activity monitoring

If you build another client (CLI player, iOS app, web SPA, etc.) let us know and we’ll list it here.

Missing an endpoint? Open an issue with your use‑case so we can prioritize documenting or adding it.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.